home *** CD-ROM | disk | FTP | other *** search
/ SGI Performance Co-Pilot 1.3 / SGI Performance Co-Pilot 1.3.iso / dist / dist6.4 / pcp.idb / usr / share / catman / u_man / cat3 / PMAPI / pmsetmode.z.z / pmsetmode.z / pmsetmode
Text File  |  1997-04-03  |  10KB  |  199 lines
  1.  
  2.  
  3.  
  4. PPPPMMMMSSSSEEEETTTTMMMMOOOODDDDEEEE((((3333))))                                                      PPPPMMMMSSSSEEEETTTTMMMMOOOODDDDEEEE((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ppppmmmmSSSSeeeettttMMMMooooddddeeee - set collection time parameters for the current PMAPI context
  10.  
  11. CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ppppccccpppp////ppppmmmmaaaappppiiii....hhhh>>>>
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////ttttiiiimmmmeeee....hhhh>>>>
  14.  
  15.      iiiinnnntttt ppppmmmmSSSSeeeettttMMMMooooddddeeee((((iiiinnnntttt mmmmooooddddeeee,,,, ssssttttrrrruuuucccctttt ttttiiiimmmmeeeevvvvaaaallll ****wwwwhhhheeeennnn,,,, iiiinnnntttt ddddeeeellllttttaaaa))))
  16.  
  17.      cccccccc ............ ----llllppppccccpppp
  18.  
  19. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  20.      ppppmmmmSSSSeeeettttMMMMooooddddeeee is used to define the collection time and/or mode for accessing
  21.      performance metrics and meta-data in the current Performance Metrics
  22.      Application Programming Interface (PMAPI) context.  This mode effects the
  23.      semantics of subsequent calls to the following PMAPI routines;
  24.      ppppmmmmFFFFeeeettttcccchhhh(3), ppppmmmmFFFFeeeettttcccchhhhAAAArrrrcccchhhhiiiivvvveeee(3), ppppmmmmLLLLooooooookkkkuuuuppppDDDDeeeesssscccc(3), ppppmmmmGGGGeeeettttIIIInnnnDDDDoooommmm(3),
  25.      ppppmmmmLLLLooooooookkkkuuuuppppIIIInnnnDDDDoooommmm(3) and ppppmmmmNNNNaaaammmmeeeeIIIInnnnDDDDoooommmm(3).
  26.  
  27.      If _m_o_d_e is PPPPMMMM____MMMMOOOODDDDEEEE____LLLLIIIIVVVVEEEE then all information is returned from the active
  28.      pool of performance metrics, as of the time that the PMAPI call is made,
  29.      and the other two parameters to ppppmmmmSSSSeeeettttMMMMooooddddeeee are ignored.  PPPPMMMM____MMMMOOOODDDDEEEE____LLLLIIIIVVVVEEEE is
  30.      the default mode when a new PMAPI context of type PPPPMMMM____CCCCOOOONNNNTTTTEEEEXXXXTTTT____HHHHOOOOSSSSTTTT is
  31.      created.
  32.  
  33.      If the _m_o_d_e is not PPPPMMMM____MMMMOOOODDDDEEEE____LLLLIIIIVVVVEEEE, then the _w_h_e_n parameter defines a time
  34.      origin, and all requests for meta-data (metrics descriptions and instance
  35.      identifiers from the instance domains) will be processed to reflect the
  36.      state of the meta-data as of the time origin, i.e. we use the last state
  37.      of this information at, or before, the time origin.
  38.  
  39.      If the _m_o_d_e is PPPPMMMM____MMMMOOOODDDDEEEE____IIIINNNNTTTTEEEERRRRPPPP then, in the case of ppppmmmmFFFFeeeettttcccchhhh(3), the
  40.      underlying code will use an interpolation scheme to compute the values of
  41.      the metrics from the values recorded for times in the proximity of the
  42.      time origin.  A mode of PPPPMMMM____MMMMOOOODDDDEEEE____IIIINNNNTTTTEEEERRRRPPPP may be used with either an archive
  43.      context, or a host context (in the latter case the subsequent PMAPI
  44.      functions will be serviced from the primary archive log maintained by
  45.      ppppmmmmllllooooggggggggeeeerrrr(1), e.g. for VCR-replay).
  46.  
  47.      If the _m_o_d_e is PPPPMMMM____MMMMOOOODDDDEEEE____FFFFOOOORRRRWWWW then, in the case of ppppmmmmFFFFeeeettttcccchhhh(3), the
  48.      collection of recorded metric values will be scanned in a forwards
  49.      direction in time, until values for at least one of the requested metrics
  50.      is located after the time origin, and then all requested metrics stored
  51.      in the log or archive at that time will be returned with the
  52.      corresponding timestamp.  A _m_o_d_e of PPPPMMMM____MMMMOOOODDDDEEEE____FFFFOOOORRRRWWWW may be used with either
  53.      an archive context, or a host context (in which case the subsequent PMAPI
  54.      functions will be serviced from the primary archive log maintained by
  55.      ppppmmmmllllooooggggggggeeeerrrr(1), e.g. for VCR-replay).
  56.  
  57.      If the _m_o_d_e is PPPPMMMM____MMMMOOOODDDDEEEE____BBBBAAAACCCCKKKK then, the situation is the same as for
  58.      PPPPMMMM____MMMMOOOODDDDEEEE____FFFFOOOORRRRWWWW, except a ppppmmmmFFFFeeeettttcccchhhh(3) will be serviced by scanning the
  59.      collection of recorded metrics in a backwards direction in time for
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. PPPPMMMMSSSSEEEETTTTMMMMOOOODDDDEEEE((((3333))))                                                      PPPPMMMMSSSSEEEETTTTMMMMOOOODDDDEEEE((((3333))))
  71.  
  72.  
  73.  
  74.      metrics before the time origin.
  75.  
  76.      If the mode is PPPPMMMM____MMMMOOOODDDDEEEE____FFFFOOOORRRRWWWW or PPPPMMMM____MMMMOOOODDDDEEEE____BBBBAAAACCCCKKKK, and no qualifying metrics
  77.      can be found in the requested direction of searching before the end or
  78.      start of the archive log is found, then ppppmmmmFFFFeeeettttcccchhhh(3) returns the special
  79.      error indicator, PPPPMMMM____EEEERRRRRRRR____EEEEOOOOLLLL.  For modes other than PPPPMMMM____MMMMOOOODDDDEEEE____LLLLIIIIVVVVEEEE, after
  80.      each successful ppppmmmmFFFFeeeettttcccchhhh(3), the time origin is reset to the timestamp
  81.      returned via the _p_m_R_e_s_u_l_t structure from ppppmmmmFFFFeeeettttcccchhhh(3).
  82.  
  83.      The ppppmmmmSSSSeeeettttMMMMooooddddeeee parameter _d_e_l_t_a defines an additional number of
  84.      milliseconds that should be used to adjust the time origin (forwards or
  85.      backwards), after the new time origin from the _p_m_R_e_s_u_l_t has been
  86.      determined.  This automatic adjustment of the time origin only occurs
  87.      when the _m_o_d_e is PPPPMMMM____MMMMOOOODDDDEEEE____IIIINNNNTTTTEEEERRRRPPPP, and the adjustment is applied, even if
  88.      the ppppmmmmFFFFeeeettttcccchhhh(3) fails because the time origin is outside the range defined
  89.      by the records in an archive log, i.e. returns PPPPMMMM____EEEERRRRRRRR____EEEEOOOOLLLL.
  90.  
  91.      Using these _m_o_d_e options, an application can implement replay, playback,
  92.      fast forward, reverse, etc. for performance metric values held in the
  93.      archive log by alternating calls to ppppmmmmSSSSeeeettttMMMMooooddddeeee and ppppmmmmFFFFeeeettttcccchhhh(3).
  94.  
  95.      For example, the following code fragment may be used to dump just those
  96.      values recorded in an archive in correct temporal sequence, for a
  97.      selected set of performance metrics; this uses the default collection
  98.      time mechanisms.
  99.  
  100.           pmNewContext(PM_CONTEXT_ARCHIVE, "myarchive");
  101.           while (pmFetchArchive(npmid, pmidlist, &result) != PM_ERR_EOL) {
  102.               /*
  103.                * process real metric values as of result->timestamp
  104.                */
  105.               . . .
  106.               pmFreeResult(result);
  107.           }
  108.  
  109.      Alternatively, to replay interpolated metrics from the log in reverse
  110.      chronological order, at 10 second intervals (of recorded time), the
  111.      following code fragment could be used.
  112.  
  113.           struct timeval mytime;
  114.  
  115.           mytime.tv_sec = 0x7fffffff;
  116.           pmSetMode(PM_MODE_BACK, &mytime, 0);
  117.           pmFetchArchive(&result);
  118.           mytime = result->timestamp;
  119.           pmFreeResult(result);
  120.           pmSetMode(PM_MODE_INTERP, &mytime, -10000);
  121.  
  122.           while (pmFetch(numpmid, pmidlist, &result) != PM_ERR_EOL) {
  123.               /*
  124.                * process interpolated metric values as of
  125.                * result->timestamp
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PPPPMMMMSSSSEEEETTTTMMMMOOOODDDDEEEE((((3333))))                                                      PPPPMMMMSSSSEEEETTTTMMMMOOOODDDDEEEE((((3333))))
  137.  
  138.  
  139.  
  140.                */
  141.               . . .
  142.               pmFreeResult(result);
  143.           }
  144.  
  145. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  146.      PPPPMMMMAAAAPPPPIIII(3), ppppmmmmFFFFeeeettttcccchhhh(3), ppppmmmmFFFFeeeettttcccchhhhAAAArrrrcccchhhhiiiivvvveeee(3), ppppmmmmGGGGeeeettttIIIInnnnDDDDoooommmm(3), ppppmmmmLLLLooooooookkkkuuuuppppDDDDeeeesssscccc(3),
  147.      ppppmmmmLLLLooooooookkkkuuuuppppIIIInnnnDDDDoooommmm(3) and ppppmmmmNNNNaaaammmmeeeeIIIInnnnDDDDoooommmm(3).
  148.  
  149. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  150.      PPPPMMMM____EEEERRRRRRRR____MMMMOOOODDDDEEEE
  151.           The _m_o_d_e parameter is invalid
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.